5. REMOTE EVENTS

With SharePoint becoming the main collaboration hub in many organizations, two-way integration with external systems (meaning external to SharePoint) has become a popular requirement over the past couple years.

Tight integration with Business Intelligence technologies such as Reporting Services, PerformancePoint, and Excel, and workloads such as Search and Business Connectivity Services have been used for surfacing external data inside SharePoint. Reversibly, SharePoint web services and CSOM have offered a set of options for surfacing SharePoint data in external systems, although in limited ways. SharePoint, however, has not provided a robust notification infrastructure for informing external systems of SharePoint events or getting notified when changes are made in the underlying data in the external systems.

Consider this scenario: The Tailspin Toys management team has issued a new mandate that the sales force in the field must provide the quickest response possible to sales leads created in its CRM system. In the past, its salespeople had to go to CRM to see the sales leads. However, with a proper notification system in place, the salespeople can be notified via SharePoint via e-mail that a sales lead has been received. The contact information for a sales lead is attached so that, when in the field, the sales representative can call the customer immediately and provide that personal touch that the senior manager wants them to have.

In the earlier versions of SharePoint, it was not easy to build an efficient solution to implement a scenario like the one for Tailspin Toys, except through some complex, full-trust farm solutions that used several custom event receivers and web service calls into CRM. One way to do this was to use pluggable workflow services in SharePoint 2010 to create custom workflow activities to implement remote event receivers. Figure 6 shows how pluggable workflow services can be utilized in SharePoint 2010 using callExternalExternalMethodActivitiy1 and hanldeExternalEventActivity1 activities. 

FIGURE 6

Given that full-trust farm solutions are not allowed in Office 365 and hosted deployments, and pluggable workflow services were poorly documented and not well received by developers, Microsoft had to come up with inherent semantics and the supporting infrastructure to enable remote events in SharePoint 2013.

To address challenges associated with cross-platform notifications, Microsoft has introduced three new options: Reporting Services data alerts, events in external lists, and remote event receivers. Now quickly review each option.

Reporting Services 2012 Data Alerts

Introduced in SQL Server 2012 and only available in SharePoint integrated mode, this new feature of Reporting Services enables you to set up alerts in reports that use stored credentials in their data source. When the underlying data in the report is changed, some recipients are notified. Because in data alerts you can specify recipient e-mail addresses (see Figure 7), a recipient can be an e-mail enabled document library where you have already registered an event receiver of type SPEmailReceiver to listen to incoming e-mails and then parse and take actions based on the information included in the From, To, Subject, Body, and Sent properties of the e-mail.

FIGURE 7

Events in External Lists

External lists in Business Connectivity Services in SharePoint 2013 support events. Two new stereotypes (Subscribe and Unsubscribe) have been added to the BCS object model to support notifications in external lists. ItemAdded, ItemUpdated, and ItemDeleted events are supported for setting up subscriptions.

Remote Event Receivers

New in SharePoint 2013, developers can register remote event receivers with SharePoint similar to the way that local event receivers are registered in SharePoint 2010. The only major difference is that the developer provides a web service URL rather than an assembly and class name in that web service that needs to be called when registering the event receiver. When the event in question occurs, SharePoint sends the event properties to the web service, and it expects information about the result of the event receiver in response.

The following code snippet shows the Element XML of a remote event receiver specified for a list deployed as part of a SharePoint-hosted App. Note how in the URL and Type elements the web service URL and type of event is specified:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers ListTemplateId="10000">
      <Receiver>
        <Name>AnnouncementsReceiverItemAdded</Name>
        <Type>ItemAdded</Type>
        <SequenceNumber>10000</SequenceNumber>
        <Url> http://tailspintoys.com/AnnouncementsReceiver.svc</Url>
      </Receiver>
  </Receivers>
</Elements>

The web service is just a public class that implements the IRemoteEventService interface and ProcessEvent for -ing events (that is, ItemAdding) before an event happens and ProcessOneWayEvent for –ed events (that is, ItemAdded) after an event happens:

public class AnnouncementsReceiver : IRemoteEventService
    {
        public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties)
        {
            SPRemoteEventResult result = new SPRemoteEventResult();
 
            switch (properties.EventType)
            {
                case RemoteEventType.ItemAdding:
                    //Code to handle ItemAdding
                    break;
 
                case RemoteEventType.ItemDeleting:
                    //Code Omitted for brevity
break;
            }
 
            return result;
        }
 
        public void ProcessOneWayEvent(RemoteEventProperties properties)
        {
            if (properties.EventType == RemoteEventType.ItemAdded)
            {
                    //Code Omitted for brevity                    
            }
 
        }

The Security Model in Remote Events

When it comes to remote events and the ability of systems to work and notify each other, a major concern is always security. Figure 8 shows how different players of a remote event scenario work together in SharePoint 2013.

FIGURE 8

Here are the basic steps as shown in Figure 8:

The following code snippet shows how a web service in the remote event receiver can obtain a context token from ACS and build a SharePoint context and the remote client context to perform a task in SharePoint:

HttpRequestMessageProperty requestPro =
(HttpRequestMessageProperty)OperationContext.
Current.IncomingMessageProperties[HttpRequestMessageProperty.Name];
string ctxTokenString = requestPro.Headers["X-SP-AccessToken"];
SharePointctxToken ctxToken = TokenHelper.ReadAndValidatectxToken(ctxTokenString,
requestPro.Headers[HttpRequestHeader.Host]);
Uri spUrl = new Uri(properties.ItemEventProperties.WebUrl);
string accessToken = TokenHelper.GetAccessToken(ctxToken, 
spUrl.Authority).AccessToken;
ClientContext clientContext = 
TokenHelper.GetClientContextWithAccessToken(spUrl.ToString(), accessToken))